Inside Macintosh: Imaging with QuickDraw
To draw a picture, use the DrawPicture procedure. You must access a picture through its handle. When creating pictures, the OpenCPicture and OpenPicture functions (described beginning on OpenCPicture ) return their handles. You can use the GetPicture function to get a handle to a QuickDraw picture stored in a 'PICT' resource.
To get a handle to a QuickDraw picture stored in a 'PICT' file, you must use File Manager routines, as described in "Drawing a Picture Stored in a 'PICT' File," . To get a picture stored in the scrap, use the Scrap Manager procedure GetScrap to get a handle to its data and then coerce this handle to one of type PicHandle , as shown in Listing 7-6 .
To draw a picture on any type of output device, use the DrawPicture procedure.
PROCEDURE DrawPicture (myPicture:PicHandle; dstRect:Rect);
Within the rectangle that you specify in the dstRect parameter, the DrawPicture procedure draws the picture that you specify in the myPicture parameter.
The DrawPicture procedure passes any picture comments to the StdComment procedure pointed to by the commentProc field of the CQDProcs or QDProcs record, which in turn is pointed to by the grafProcs field of a CGrafPort or GrafPort record. The default StdComment procedure provided by QuickDraw does no comment processing whatsoever. If you want to process picture comments when drawing a picture, you can use the SetStdCProcs procedure to assist you in changing the CQDProcs record, and you can use the SetStdProcs procedure to assist you in changing the QDProcs record.
Always use the ClipRect procedure to specify a clipping region appropriate for your picture before defining it with the OpenCPicture (or OpenPicture ) function. If you do not use ClipRect to specify a clipping region, OpenCPicture uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you want to scale the picture, the clipping region can become invalid when DrawPicture scales the clipping region--in which case, your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when DrawPicture draws it. Setting a clipping region equal to the port rectangle of the current graphics port, as shown in Listing 7-1 , always sets a valid clipping region.
When it scales, DrawPicture changes the size of the font instead of scaling the bits. However, the widths used by bitmap fonts are not always linear. For example, the 12-point width isn't exactly 1/2 of the 24-point width. This can cause lines of text to become slightly longer or shorter as the picture is scaled. The difference is often insignificant, but if you are trying to draw a line of text that fits exactly into a box (a spreadsheet cell, for example), the difference can become noticeable to the user--most typically, at print time. The easiest way to avoid such problems is to specify a destination rectangle that is the same size as the bounding rectangle for the picture. Otherwise, your application may need to directly process the opcodes in the picture instead of using DrawPicture .
You may also have disappointing results if the fonts contained in an image are not available on the user's system. Before displaying a picture, your application may want to use the Picture Utilities to determine what fonts are contained in the picture, and then use Font Manager routines to determine whether the fonts are available on the user's system. If they are not, you can use Dialog Manager routines to display an alert box warning the user of display problems.
If there is insufficient memory to draw a picture in Color QuickDraw, the QDError function (described in the chapter "Color QuickDraw" in this book) returns the result code noMemForPictPlaybackErr .
Listing 7-1 illustrates how to use DrawPicture after creating a picture while your application is running; Listing 7-2 illustrates how to use DrawPicture after reading in a picture stored in a 'PICT' file; Listing 7-6 illustrates how to use DrawPicture after reading in a picture stored in the scrap; and Listing 7-8 illustrates how to use DrawPicture after reading in a picture stored in a 'PICT' resource.
See the chapter "Font Manager" in Inside Macintosh: Text for information about Font Manager routines; see the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information about Dialog Manager routines.
Use the GetPicture function to get a handle to a picture stored in a 'PICT' resource.
FUNCTION GetPicture (picID: Integer): PicHandle;
The GetPicture function returns a handle to the picture stored in the 'PICT' resource with the ID that you specify in the picID parameter. You can pass this handle to the DrawPicture procedure (described on DrawPicture ) to draw the picture stored in the resource.
The GetPicture function calls the Resource Manager procedure GetResource as follows:
GetResource('PICT',picID)
To release the memory occupied by a picture stored in a 'PICT' resource, use the Resource Manager procedure ReleaseResource .
The GetResource and ReleaseResource procedures are described in the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox . The 'PICT' resource is described on The Picture Resource .